From c7641c24b5e42a9fe223e4519f25e58025ac3c52 Mon Sep 17 00:00:00 2001 From: Pierre Krieger Date: Tue, 21 Oct 2014 16:38:29 +0200 Subject: [PATCH] Add general doccomments --- src/cargo/core/dependency.rs | 20 ++++++++++++++++++++ src/cargo/core/manifest.rs | 6 ++++++ src/cargo/core/package.rs | 3 +++ src/cargo/core/package_id.rs | 1 + src/cargo/core/registry.rs | 4 ++++ src/cargo/core/resolver.rs | 2 ++ src/cargo/core/source.rs | 17 +++++++++++++++++ src/cargo/core/summary.rs | 2 ++ src/cargo/ops/cargo_compile.rs | 4 ++++ src/cargo/ops/cargo_fetch.rs | 5 +++++ 10 files changed, 64 insertions(+) diff --git a/src/cargo/core/dependency.rs b/src/cargo/core/dependency.rs index fd3e5b961..2585d6e34 100644 --- a/src/cargo/core/dependency.rs +++ b/src/cargo/core/dependency.rs @@ -2,6 +2,7 @@ use core::{SourceId,Summary}; use semver::VersionReq; use util::CargoResult; +/// Informations about a dependency requested by a Cargo manifest. #[deriving(PartialEq,Clone,Show)] pub struct Dependency { name: String, @@ -16,6 +17,16 @@ pub struct Dependency { } impl Dependency { + /// Attempt to create a `Dependency` from an entry in the manifest. + /// + /// ## Example + /// + /// ``` + /// use cargo::core::SourceId; + /// use cargo::core::Dependency; + /// + /// Dependency::parse("color", Some("1.*"), SourceId::for_central()) + /// ``` pub fn parse(name: &str, version: Option<&str>, source_id: &SourceId) -> CargoResult { @@ -44,6 +55,7 @@ impl Dependency { } } + /// Returns the version of the dependency that is being requested. pub fn get_version_req(&self) -> &VersionReq { &self.req } @@ -52,6 +64,7 @@ impl Dependency { self.name.as_slice() } + /// Returns the place where this dependency must be searched for. pub fn get_source_id(&self) -> &SourceId { &self.source_id } @@ -61,26 +74,33 @@ impl Dependency { self } + /// Sets the list of features requested for the package. pub fn features(mut self, features: Vec) -> Dependency { self.features = features; self } + /// Sets whether the dependency requests default features of the package. pub fn default_features(mut self, default_features: bool) -> Dependency { self.default_features = default_features; self } + /// Sets whether the dependency is optional. pub fn optional(mut self, optional: bool) -> Dependency { self.optional = optional; self } + /// Returns false if the dependency is only used to build the local package. pub fn is_transitive(&self) -> bool { self.transitive } pub fn is_optional(&self) -> bool { self.optional } + /// Returns true if the default features of the dependency are requested. pub fn uses_default_features(&self) -> bool { self.default_features } + /// Returns the list of features that are requested by the dependency. pub fn get_features(&self) -> &[String] { self.features.as_slice() } + /// Returns true if the package (`sum`) can fulfill this dependency request. pub fn matches(&self, sum: &Summary) -> bool { debug!("matches; self={}; summary={}", self, sum); debug!(" a={}; b={}", self.source_id, sum.get_source_id()); diff --git a/src/cargo/core/manifest.rs b/src/cargo/core/manifest.rs index ac3629eb4..e274dbbc2 100644 --- a/src/cargo/core/manifest.rs +++ b/src/cargo/core/manifest.rs @@ -14,6 +14,7 @@ use core::package_id::Metadata; use core::dependency::SerializedDependency; use util::{CargoResult, human}; +/// Contains all the informations about a package, as loaded from a Cargo.toml. #[deriving(PartialEq,Clone)] pub struct Manifest { summary: Summary, @@ -89,6 +90,7 @@ impl LibKind { strings.iter().map(|s| LibKind::from_str(s.as_slice())).collect() } + /// Returns the argument suitable for `--crate-type` to pass to rustc. pub fn crate_type(&self) -> &'static str { match *self { Lib => "lib", @@ -303,6 +305,7 @@ impl hash::Hash for Profile { } } +/// Informations about a binary, a library, an example, etc. that is part of the package. #[deriving(Clone, Hash, PartialEq)] pub struct Target { kind: TargetKind, @@ -399,6 +402,7 @@ impl Manifest { &self.doc_dir } + /// Returns a list of all the potential `SourceId`s of the dependencies. pub fn get_source_ids(&self) -> &[SourceId] { self.sources.as_slice() } @@ -520,6 +524,7 @@ impl Target { } } + /// Returns true for binary, bench, tests and examples. pub fn is_bin(&self) -> bool { match self.kind { BinTarget => true, @@ -535,6 +540,7 @@ impl Target { self.metadata.as_ref() } + /// Returns the arguments suitable for `--crate-type` to pass to rustc. pub fn rustc_crate_types(&self) -> Vec<&'static str> { match self.kind { LibTarget(ref kinds) => { diff --git a/src/cargo/core/package.rs b/src/cargo/core/package.rs index fb41ee1a3..f0e65e7d8 100644 --- a/src/cargo/core/package.rs +++ b/src/cargo/core/package.rs @@ -15,6 +15,9 @@ use util::{CargoResult, graph}; use serialize::{Encoder,Encodable}; use core::source::{SourceId, Source}; +/// Informations about a package that is available somewhere in the file system. +/// +/// A package is a `Cargo.toml` file, plus all the files that are part of it. // TODO: Is manifest_path a relic? #[deriving(Clone)] pub struct Package { diff --git a/src/cargo/core/package_id.rs b/src/cargo/core/package_id.rs index e5e657677..855272e96 100644 --- a/src/cargo/core/package_id.rs +++ b/src/cargo/core/package_id.rs @@ -9,6 +9,7 @@ use regex::Regex; use util::{CargoResult, CargoError, short_hash, ToSemver}; use core::source::SourceId; +/// Identifier for a specific version of a package in a specific source. #[deriving(Clone, PartialEq, PartialOrd, Ord)] pub struct PackageId { name: String, diff --git a/src/cargo/core/registry.rs b/src/cargo/core/registry.rs index 5d95bcb15..007cf4b76 100644 --- a/src/cargo/core/registry.rs +++ b/src/cargo/core/registry.rs @@ -3,7 +3,11 @@ use std::collections::HashSet; use core::{Source, SourceId, SourceMap, Summary, Dependency, PackageId, Package}; use util::{CargoResult, ChainError, Config, human, profile}; +/// Source of informations about a group of packages. +/// +/// See also `core::Source`. pub trait Registry { + /// Attempt to find the packages that match a dependency request. fn query(&mut self, name: &Dependency) -> CargoResult>; } diff --git a/src/cargo/core/resolver.rs b/src/cargo/core/resolver.rs index 388220d28..2e846e315 100644 --- a/src/cargo/core/resolver.rs +++ b/src/cargo/core/resolver.rs @@ -11,6 +11,7 @@ use util::{CargoResult, Graph, human, internal, ChainError}; use util::profile; use util::graph::{Nodes, Edges}; +/// Result of the `resolve` function. #[deriving(PartialEq, Eq)] pub struct Resolve { graph: Graph, @@ -301,6 +302,7 @@ impl<'a, R: Registry> Context<'a, R> { } } +/// Builds the list of all packages required to build the first argument. pub fn resolve(summary: &Summary, method: ResolveMethod, registry: &mut R) -> CargoResult { log!(5, "resolve; summary={}", summary); diff --git a/src/cargo/core/source.rs b/src/cargo/core/source.rs index e89eefca8..423b5d9a3 100644 --- a/src/cargo/core/source.rs +++ b/src/cargo/core/source.rs @@ -56,6 +56,7 @@ pub enum SourceKind { type Error = Box; +/// Unique identifier for a source of packages. #[deriving(Clone, Eq)] pub struct SourceId { pub url: Url, @@ -158,6 +159,16 @@ impl SourceId { SourceId { kind: kind, url: url, precise: None } } + /// Parses a source URL and returns the corresponding ID. + /// + /// ## Example + /// + /// ``` + /// use cargo::core::SourceId; + /// SourceId::from_url("git+https://github.com/alexcrichton/\ + /// libssh2-static-sys#80e71a3021618eb05\ + /// 656c58fb7c5ef5f12bc747f".to_string()) + /// ``` pub fn from_url(string: String) -> SourceId { let mut parts = string.as_slice().splitn(1, '+'); let kind = parts.next().unwrap(); @@ -235,6 +246,10 @@ impl SourceId { SourceId::new(RegistryKind, url.clone()) } + /// Returns the `SourceId` corresponding to the main repository. + /// + /// This is the main cargo registry by default, but it can be overridden in + /// a `.cargo/config`. pub fn for_central() -> CargoResult { Ok(SourceId::for_registry(&try!(RegistrySource::url()))) } @@ -254,6 +269,7 @@ impl SourceId { } } + /// Creates an implementation of `Source` corresponding to this ID. pub fn load<'a>(&self, config: &'a mut Config) -> Box { log!(5, "loading SourceId; {}", self); match self.kind { @@ -334,6 +350,7 @@ impl<'a> SourceMap<'a> { } } +/// List of `Source` implementors. `SourceSet` itself implements `Source`. pub struct SourceSet<'a> { sources: Vec> } diff --git a/src/cargo/core/summary.rs b/src/cargo/core/summary.rs index 582f988f0..b794f8db4 100644 --- a/src/cargo/core/summary.rs +++ b/src/cargo/core/summary.rs @@ -5,6 +5,8 @@ use core::{Dependency, PackageId, SourceId}; use util::{CargoResult, human}; +/// Subset of a `Manifest`. Contains only the most important informations about a package. +/// /// Summaries are cloned, and should not be mutated after creation #[deriving(Show,Clone,PartialEq)] pub struct Summary { diff --git a/src/cargo/ops/cargo_compile.rs b/src/cargo/ops/cargo_compile.rs index 01f10f6a7..438947a4b 100644 --- a/src/cargo/ops/cargo_compile.rs +++ b/src/cargo/ops/cargo_compile.rs @@ -33,11 +33,15 @@ use sources::{PathSource}; use util::config::{Config, ConfigValue}; use util::{CargoResult, Wrap, config, internal, human, ChainError, profile}; +/// Contains informations about how a package should be compiled. pub struct CompileOptions<'a> { pub env: &'a str, pub shell: &'a mut MultiShell<'a>, + /// Number of concurrent jobs to use. pub jobs: Option, + /// The target platform to compile for (example: `i686-unknown-linux-gnu`). pub target: Option<&'a str>, + /// True if dev-dependencies must be compiled. pub dev_deps: bool, pub features: &'a [String], pub no_default_features: bool, diff --git a/src/cargo/ops/cargo_fetch.rs b/src/cargo/ops/cargo_fetch.rs index 310b18ca5..e8820df8b 100644 --- a/src/cargo/ops/cargo_fetch.rs +++ b/src/cargo/ops/cargo_fetch.rs @@ -9,6 +9,7 @@ use sources::PathSource; use util::{CargoResult, Config}; use util::profile; +/// Executes `cargo fetch`. pub fn fetch(manifest_path: &Path, shell: &mut MultiShell) -> CargoResult<()> { let mut source = try!(PathSource::for_path(&manifest_path.dir_path())); @@ -21,6 +22,10 @@ pub fn fetch(manifest_path: &Path, Ok(()) } +/// Finds all the packages required to compile the specified `Package`, +/// and loads them in the `PackageRegistry`. +/// +/// Also write the `Cargo.lock` file with the results. pub fn resolve_and_fetch(registry: &mut PackageRegistry, package: &Package) -> CargoResult { let _p = profile::start("resolve and fetch..."); -- 2.30.2